﻿<HTML>

<HEAD>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8" />  
  <TITLE>Sample and User Projects</TITLE>
  <LINK HREF="doc.css" REL=STYLESHEET>
</HEAD>


<BODY>


<!-- ============================================ -->


  <TABLE CLASS="header">
    <TBODY>
      <TR>
        <TD CLASS="head">Sample and User Projects</TD>
        <TD CLASS="logo" ROWSPAN="2"><IMG CLASS="logosmall" SRC="../images/heo-logo.png"></IMG></TD>
      </TR>
      <TR>
        <TD CLASS="links"><A HREF="solvers.html">[Previous]</A><A HREF="style.html">[Next]</A><A HREF="../index.html">[Home]</A></TD>
      </TR>
    </TBODY>
  </TABLE>


  <H2>Contents</H2>

  <UL>
    <LI><A HREF="#overview">Overview</A></LI> 
    <LI><A HREF="#generic">Generic Projects</A></LI> 
    <LI><A HREF="#onemax">ONE-MAX Projects</A></LI> 
    <LI><A HREF="#maxsat">MAX-SAT Projects</A></LI> 
    <LI><A HREF="#other">Other Sample Projects</A></LI> 
    <LI><A HREF="#creating">Creating User Projects</A></LI> 
    <LI><A HREF="#building">Building Projects</A></LI> 
    <LI><A HREF="#runnig">Running Projects</A></LI> 
  </UL>


<!-- ============================================ -->


  <A NAME="overview"></A>
  <H3>Overview</H3>

  <P>
    There are many sample projects for several optimization problems provided with the HeO library.
    The main goal of these projects is to help users to understand the HeO architecture.
    All projects can be compiled under Windows and Linux (please check <A HREF="heo.html#sysreq">System Requirements</A>).
   </P> 

  <P>
    All sample and user projects are stored in the <TT CLASS="folder">/heo/projects</TT> folder.
    Projects for different optimization problems are stored in separate subfolders.
  </P> 


<!-- ============================================ -->


  <A NAME="generic"></A>
  <H3>Generic Projects</H3>

  <P>
    In the generic projects no optimization problem is solved. 
    The goal of these projects is to demonstrate the usage of the HeO solvers. 
    Problem-specific classes in these projects implement only those methods that are specific to the particular optimization technique.
    These methods are implemented as program stubs that perform no action and allow to compile the projects without errors.
  </P> 


  <P>
    The generic projects are stored in the <TT CLASS="folder">/heo/projects/generic</TT> folder. 
    Projects for different optimization techniques are stored in separate subfolders (e.g., <TT CLASS="folder">/heo/projects/generic/ga</TT>, <TT CLASS="folder">/heo/projects/generic/sa</TT>).
    Projects for different solvers of the same optimization technique are stored in separate subfolders (e.g., <TT CLASS="folder">/heo/projects/generic/ga/mpi</TT>, <TT CLASS="folder">/heo/projects/generic/ga/omp</TT>).
  </P> 


  <P>
    These projects do not need any input files.
    The zero value of the dummy variable is stored in the <TT>&lt;generic.../&gt;</TT> node of the configuration files.
  </P> 


<!-- ============================================ -->


  <A NAME="onemax"></A>
  <H3>ONE-MAX Projects</H3>

  <P>
    The ONE-MAX problem is a simple combinatorial optimization problem that is often used to test optimization algorithms.  
    Its goal is to maximize the number of 1s in a bit string.
  </P> 


  <P>
    The projects for this problem do not need any input files.
    The configuration files for these projects store the total number of bits in the string in the <TT>dimension</TT> attribute of the <TT>&lt;onemax.../&gt;</TT> node.
  </P> 


<!-- ============================================ -->


  <A NAME="maxsat"></A>
  <H3>MAX-SAT Projects</H3>

  <P>
    In the Maximum Satisfiability Problem (MAX-SAT) a Boolean formula in conjunctive normal form (CNF) is given.
    The goal of this combinatorial problem is to find a set of truth variables that maximizes the number of satisfied clauses.
  </P> 
  
  <P>
    The MAX-SAT projects are stored in the respective subfolders of the <TT CLASS="folder">/heo/projects/maxsat</TT> folder.
    The input files for these projects are stored in the <TT CLASS="folder">/heo/problems/maxsat</TT> folder and have to be in CNF format without comments as it is shown below: 
  </P> 

  <DIV CLASS="code">
    p cnf 500 1000<BR>
    300 -128 0<BR>
    212 -210 188 0<BR>
    -139 123 -33 2 -5 0<BR>
    190 -358 202 0<BR>
    -417 101 0<BR>
    ...
  </DIV>

  <P>
    The first string of the file specifies that this problem is in CNF format and has 500 variables and 1000 clauses. 
    Next lines describe the clauses of the Boolean formula.
    In the above example the formula is as follows: 
    (<I>x<SUB>300</SUB></I>&or;&not;<I>x<SUB>128</SUB></I>)&and;(<I>x<SUB>212</SUB></I>&or;&not;<I>x<SUB>210</SUB></I>&or;<I>x<SUB>188</SUB></I>)&and;&hellip;
  </P> 
  

<!-- ============================================ -->


  <A NAME="other"></A>
  <H3>Other Sample Projects</H3>

  <P>
    There are some other sample projects for several optimization problems.
    These problems are:
  </P> 

  <UL>
    <LI>QAP &mdash; Quadratic Assignment Problem.</LI>
    <LI>GRIDMIN &mdash; Minimization of the covering grids number in the matrices associated with the nondeterministic finite automata.</LI>
    <LI>ODE1IVP &mdash; Numeric solution of initial value problems for odinary differential equations of the first order.</LI>
    <LI>RASTRIGIN &mdash; Minimization of Rastrigin function.</LI>
  </UL>


<!-- ============================================ -->


  <A NAME="creating"></A>
  <H3>Creating User Projects</H3>

  <P>
    The library provides special wizards that ease the process of creating user projects.
    Each project is aimed to solve the particular optimization problem by the particular optimizaton method. 
    Wizards for Linux and Windows systems are called <TT>wizard_new.sh</TT> and <TT>wizard_new.vbs</TT> respectively. 
    They are stored in the <TT CLASS="folder">/heo/projects</TT> folder.
  </P>


  <P>
    To create a new project: 
  </P>

  <OL>
    <LI>Run the wizard and provide the problem name.
        All necessary subfolders and source files in the <TT CLASS="folder">/heo/projects</TT> and <TT CLASS="folder">/heo/problems</TT> folders will be created automatically.</LI>
    <LI>Modify problem-specific classes.</LI> 
    <LI>If needed, copy the input files containing problem instances to the <TT CLASS="folder">/heo/problems/&lt;problem&nbsp;name&gt;</TT> folder.</LI>
  </OL>


  <P>
    <B>Note.</B> The names of the created projects are automatically composed from the problem, optimization method and parallel technology names (e.g., <TT>maxsat_ga_mpi.vcproj</TT>). 
  </P>

<!-- ============================================ -->


  <A NAME="building"></A>
  <H3>Building Projects</H3>


  <P>
    <B>Building Projects under Linux</B>
  </P>

  <UL>
    <LI>To compile the desired project change to its folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/ga/mpi</TT>) and run <TT>make</TT> command.</LI>
    <LI>To compile all sample projects change to the <TT CLASS="folder">/heo/projects/all</TT> folder and run <TT>make</TT> command.</LI>
  </UL> 

  <P>
    <B>Note.</B> The GCC compiler is assumed by default for Linux. If you wish to use another compiler you may need to modify the following files in the <TT CLASS="folder">/heo/src/heo/include</TT> folder: 
  </P>

  <UL>
    <LI><TT>mpi.makefile</TT>.</LI> 
    <LI><TT>omp.makefile</TT>.</LI> 
    <LI><TT>common.makefile</TT>.</LI> 
  </UL>

  <P>
    The first two files contain the MPI "wrapper" compiler name (<TT>HEO_CXX = mpiCC</TT>) and the OpenMP compiler name (<TT>HEO_CXX = g++</TT>) respectively and their options.
    The third file contains all information for building the projects.
  </P>

  <P>
     For example, if you wish to build OpenMP projects using Intel C++ Compiler you have to modify the <TT>omp.makefile</TT> as follows:
  </P>

  <DIV CLASS="code">
    HEO_CXX = icpc<BR>
    HEO_CXXFLAGS = -I. -I$(HEO_PATH) -openmp -openmp-lib=compat
  </DIV>

  <P>
     Building MPI projects using Intel C++ Compiler under Linux may be more complicated.
     If the <TT>mpicxx</TT> is a text script you can find the <TT>g++</TT> string in it and replace it with <TT>icpc</TT>.
     If the <TT>mpicxx</TT> isn't a text script then you have to build the MPI itself using Intel C++ Compiler (please refer to MPI documentation).
  </P>



  <P>
    <B>Building Projects under Windows</B>
  </P>

  <UL>
    <LI>To compile the desired project change to its folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/ga/mpi</TT>), run the <TT>*.vcproj</TT> (or <TT>*.sln</TT>) file, select the <TT>Release</TT> configuration and build the project.</LI>
    <LI>To compile all sample projects change to the <TT CLASS="folder">/heo/projects/all</TT> folder, run <TT>all.sln</TT> file, select the <TT>Release</TT> configuration and build the projects.</LI>
  </UL> 

  <P>
    <B>Note.</B> The MS VC++ compiler is assumed by default for Windows. If you wish to use Intel C++ Compiler you have to integrate it with the MS Visual Studio. 
  </P>


<!-- ============================================ -->


  <A NAME="running"></A>
  <H3>Running Projects</H3>

  <P>
    There are special wizards in the HeO library that ease the process of creating command files for running the compiled projects on different platforms.
    For Linux and Windows systems these wizards are called <TT>wizard_run.sh</TT> and <TT>wizard_run.vbs</TT> respectively. 
    They are stored in the <TT CLASS="folder">/heo/projects</TT> folder.
  </P>

  <P>
    To create command files run the wizard and select all necessary parameters: problem name, optimization method, etc. 
    Note, that not all combinations of the selected parameters may be valid.
    The created command files will be saved to <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/run</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/run</TT>).
  </P>


  <P>
    To run the compiled projects use the appropriate command files in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/run</TT> folder.
    By default, the results of the project runs are stored in the <TT CLASS="folder">/heo/projects/&lt;problem&nbsp;name&gt;/res/&lt;problem&nbsp;instance&nbsp;name&gt;</TT> folder (e.g., <TT CLASS="folder">/heo/projects/maxsat/res/sample</TT>).
  </P>

  <P>
    <B>Note.</B> 
    Before running the project you have to create the <TT>*.xml</TT> configuration file.
    If the <TT>*.xml</TT> configuration file indicated in the command file does not exist it will be created automatically after the first project run and its parameters will be set to the default values.
  </P>

<!-- ============================================ -->


<H2>&nbsp;</H2>

<A HREF="solvers.html">[Previous]</A><A HREF="style.html">[Next]</A><A HREF="../index.html">[Home]</A>


<!-- ============================================ -->


</BODY>

</HTML>


